1. 拼接URL
- 格式：
- 示例：
2. 浏览器打开拼接好的 URL
3. 用户选项目，点“下一步”
4. 跳转到上面配置的跳转 URL，传递 code 参数及授权的项目 resource 参数，和回传 state 参数
- 例子：
- 注意
5. 使用 code 获取 access_token
6. 使用 access_token 做为参数，调用接口

# 是否合适使用 OAuth


鉴权方式
面向群体
面向场景
使用难度
使用成本
授权流程
授权等待时间
申请材料
申请地址

# 整体流程

应用接入方 ->> TAPD 对接（anyechen）:提交应用资料（名称、logo、跳转URL、权限、access_token 续期模式、应用场景）
TAPD 对接（anyechen） ->> 应用接入方:审批，发放 client_id、client_secret
应用接入方->> apiv2.tapd.oa.com: 开发调试及上线应用

1
2
3
4

# 理解 OAuth2.0

# 接入方接入准备

应用名称：如任务提测
redirect_uri：跳转 URL，用来接受跳转回来后的 code 等参数。可以提供多个
负责人名单
logo：大小 68x19，如：
access_token 续期模式（两者二选一）

永久 access_token
使用 refresh_token 定时刷新，使用方法参考：http://tapd.oa.com/oaopentapd/markdown_wikis/0#1020417300009665003

scope，即 API 接口权限，可取多个值，目前支持取值如下表：

取值	权限详细说明
bug	读取并写入项目缺陷
story	读取并写入项目需求
task	读取并写入项目任务
iteration	读取并写入项目迭代
tcase	读取并写入项目测试用例
wiki	读取并写入项目wiki
webhook	读取并写入项目webhook配置
release	获取并写入项目发布计划和发布评审
devops	读取并写入项目流水线和关联提交相关数据
workspace#read	读取项目信息

# 接入方使用过程

# 1. 拼接URL

# 格式：

http://tapd.oa.com/oauth/?response_type=code&client_id=%s&redirect_uri=%s&scope=%s&state=%s&auth_by=%s 注意：

取多个 scope，使用空格分隔，如story bug；
里面参数要经过 urlencode。比如 scope 取 story bug ，urlencode 后则是 story%20bug 或者 story+bug
auth_by 目前支持workspace(用户管理的项目)、take_park_workspace(用户参与的项目)两种认证方式，默认workspace

# 示例：

http://tapd.oa.com/oauth/?response_type=code&client_id=demo&redirect_uri=http://lion.oa.com/~anyechen/code/php/oauth_demo/hey.php&scope=bug%20story&auth_by=workspace&state=random_string

# 2. 浏览器打开拼接好的 URL

图片描述

# 3. 用户选项目，点“下一步”

图片描述

# 4. 跳转到上面配置的跳转 URL，传递 `code 参数`及授权的项目 `resource 参数`，和`回传 state 参数`

# 例子：

http://lion.oa.com/~anyechen/code/php/oauth_demo/hey.php?code=82a65674bd67e26e034967f5d72e17e8a4b6d395&state=random_string&resouce=%7B%22type%22%3A%22workspace%22%2C%22workspace_id%22%3A10022001%7D'

Array
(
    [code] => dbd1206cc059dc453a8bf321d0cc1d07a7814157
    [state] => random_string
    [resouce] => {"type":"workspace","workspace_id":10022001}
)

1
2
3
4
5
6

# 注意

返回的 resource ，会带上当前授权的项目ID，只能获取这个项目下的数据
code 的有效期为五分钟

# 5. 使用 code 获取 access_token

# 请求 URL

https://apiv2.tapd.tencent.com/tokens/request_token

# 请求方法

POST

# 参数要求

# POST 参数

参数	说明
`grant_type`	必须取值 authorization_code
`redirect_uri`	为配置的跳转 uri
`code`	为从链接参数上取得的 code

# 其它参数

假设发放的 client_id 为 Aladdin，client_secret为open sesame，则处理步骤举例如下：

将 Aladdin:open sesame 通过 BASE64 编码为：QWxhZGRpbjpvcGVuIHNlc2FtZQ==
写入 HTTP 头部的 Authorization 信息为：

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

# 返回

返回参数	参数说明
access_token	访问 API 的凭据
expires_in	有效时长，单位为秒
token_type	凭据类型，都是 Bearer
scope	接口范围
resource	项目权限范围
now	服务器当前时间

# 示例

# 示例请求

curl -u "client_id:client_secret" -d "grant_type=authorization_code&redirect_uri=http://lion.oa.com/~anyechen/code/php/oauth_demo/hey.php&code=82a65674bd67e26e034967f5d72e17e8a4b6d395" "https://apiv2.tapd.tencent.com/tokens/request_token"

# 示例返回

{
    "status": 1,
    "data": {
        "access_token": "7152e30d9c5b1310df6be03d88d714aaf687a595",
        "expires_in": 7200,
        "token_type": "Bearer",
        "scope": "bug story",
        "resource": {
            "type": "workspace",
            "workspace_id": 10104801
        },
        "now": "2019-06-04 16:07:51"
    },
    "info": "success"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 6. 使用 access_token 做为参数，调用接口

只需要在 http header 传 access_token 参数，如： curl -H 'Authorization: Bearer ACCESS_TOKEN' 'https://apiv2.tapd.tencent.com/bugs?workspace_id=10022001&fields=id,title'

← client_credentials 模式使用 BasicAuth和OAuth的区别 →